<!DOCTYPE html>

<html lang="en">
&&beginPlaceholder {
    "className": "com.credibledoc.substitution.content.generator.resource.FragmentGenerator",
    "description": "Insert 'header' fragment to the html page.",
    "parameters": {
        "fragmentRelativePath": "credible-doc-generator/src/main/resources/fragment/header.html"
    },
    "jsonObject": {
        "title": "Credible documentation - main page",
        "linkPrefix": ""
    }
} &&endPlaceholder
<section>
    <nav>
        <ul>
            <li class="menu-li">
                <a class="menu-a" onclick="show('credible-doc-generator', this)">Content generation</a>
            </li>
            <li class="menu-li">
                <a class="menu-a" onclick="show('substitution-parent', this)">Content substitution</a>
            </li>
            <li class="menu-li">
                <a class="menu-a" onclick="show('plantuml', this)">Diagrams generation</a>
            </li>
            <li class="menu-li">
                <a class="menu-a" onclick="show('log-combiner-parent', this)">Log files parsing</a>
            </li>
            <li class="menu-li">
                <a class="menu-a" onclick="show('iso-8583-packer', this)">Other utilities</a>
            </li>
        </ul>
    </nav>
    <article>
        <svg id="hamburger" viewBox="0 0 100 80">
            <rect width="100" height="15"></rect>
            <rect y="30" width="100" height="15"></rect>
            <rect y="60" width="100" height="15"></rect>
        </svg>
        <div class="article-h2">
            <h2>Motivation</h2>
            <p>
                The maintenance of software documentation is a complex task.
                As the time runs and the documented software is changed the documentation is getting obsolete.
                Changing documentation between versions is a boring and uncreative job.
            </p>
            <p>
                We want to reduce effort to accomplish this task.
            </p>
            <p>
                The page presents some tools for preventing the erosion of documentation
                and the fatique of analysts' minds.
            </p>
        </div>

        <div>
            <div id="credible-doc-generator" class="closable">
                <h3>
                    <img src="img/index/masonry-trowel.png" style="padding-right: 10px" alt="Image Content generation.">
                    Content generation
                </h3>
                <p>
                    There are two parts of the documentation - generated and handwritten.
                    Both have advantages and disadvantages. The generated documentation, for example javaDoc,
                    is easily maintained, because it is placed close to the source code.
                    But it has an insufficient context. 
                    The handwritten documentation describes an application behavior more comprehensible, but
                    it is insufficient in detail. It can become outdated with some changes of the application.
                </p>
                <p>
                    We want to preserve the legibility of the documents but at the same time
                    we need to avoid the outdated documentation.
                </p>
                <p>
                    In order to achieve the goal, the
                    <a href="https://github.com/credibledoc/credible-doc/blob/master/credible-doc-generator/README.md">following example</a>
                    shows how the handwritten content can be mixed with the generated parts.
                </p>
            </div>
            <div id="substitution-parent" class="closable">
                <h3>
                    <img src="img/index/adjustable_spanner.png" style="padding-right: 10px" alt="Image Content substitution.">
                    Content substitution
                </h3>
                <p>
                    There are many excellent libraries for content generation, for example:
                    <a href="https://www.thymeleaf.org/">Thymeleaf</a>,
                    <a href="https://velocity.apache.org/">Velocity</a> or
                    <a href="https://en.wikipedia.org/wiki/JavaServer_Pages">JSP</a>.
                    Our approach is simpler and we hope the learning time you spend on our tool will be shorter.
                </p>
                <p>
                    Our tools and libraries for replacing
                    <a href="https://github.com/credibledoc/credible-doc/blob/master/substitution/README.md">placeholders with a generated content</a>.
                </p>
            </div>
            <div id="plantuml" class="closable">
                <h3>
                    <img src="img/index/diagram.png" style="padding-right: 10px" alt="Image Diagrams generation.">
                    Diagrams generation
                </h3>
                <p>
                    <a href="https://plantuml.com/">PlantUML</a> is a component that allows to write diagrams quickly, in a simple and intuitive language.
                    We suggest using the language in the documentation in form of generated parts.
                </p>
                <p>
                    We introduce <a href="https://github.com/credibledoc/credible-doc/blob/master/plantuml/README.md">diagram generation utilities</a>
                    based on the PlantUML library.
                </p>
            </div>
            <div id="log-combiner-parent" class="closable">
                <h3>
                    <img src="img/index/handsaw.png" style="padding-right: 10px" alt="Image Log files parsing.">
                    Log files parsing
                </h3>
                <p>
                    Application logs are the best source for investigation of an application behavior.
                    We suggest using log files for the generation of diagrams and other documentation parts.
                </p>
                <p>
                    The <a href="https://github.com/credibledoc/credible-doc/blob/master/log-combiner-parent/README.md">log-combiner tool</a>
                    merges log files with different time formats creating a single file. All lines in the merged file are sorted by timestamp.
                </p>
                <p>
                    The merged application log can be used as a data supplier for the generated documentation. 
                </p>
            </div>
            <div id="iso-8583-packer" class="closable">
                <h3>
                    <img src="img/index/hammer.png" style="padding-right: 10px" alt="Image Other utilities.">
                    Other utilities
                </h3>
                <p>
                    The <a href="https://github.com/credibledoc/credible-doc/blob/master/iso-8583-packer/README.md">ISO 8583 packer</a>
                    utility is not related to the documentation tools.
                    But it can be useful for a payment software development and it uses <i>credible-doc</i> tools for its documentation.
                </p>
            </div>
        </div>
        
    </article>
</section>
&&beginPlaceholder {
    "className": "com.credibledoc.substitution.content.generator.resource.FragmentGenerator",
    "description": "Inserting 'footer' fragment",
    "parameters": {
        "fragmentRelativePath": "credible-doc-generator/src/main/resources/fragment/footer.html"
    },
    "jsonObject": {
        "linkPrefix": ""
    }
} &&endPlaceholder
</html>